Lesson 2: Variables
By: Darkwulfv,edited by wyrmlord

What is a variable?
-A variable is sort of like a place holder for a handle or other object. There are 2 types of variables. Local and Global.

What is the difference between Local and Global variables?
-Local variables are variables only usable by the function they’re declared in. These are used for cleaning Memory Leaks (which will be explained later), neatening code, and making script Multi-instanceable.
-Globals are variables which can be accessed by any function, but can also be changed by any function. This can be bad for multi-instanceability (which will now be referred to as MUI), depending. MUI will be discussed later on.

How do I create a local variable?
-There are two ways to creating/setting a variable.

function variable_test takes nothing returns nothing
 local unit u = CreateUnit()
endfunction

This method creates and sets it in one line, at the beginning of the function.

function variable_test takes nothing returns nothing
 local unit u
    set u = CreateUnit(…..) //Creates a unit and sets the variable to it
endfunction

And this method creates a blank variable, to be set later on in the function.

Hey wait! I want the value to change, does that mean I need a new variable?
-No, not necessarily. All you need to do is put “set your_variable = newvalue
Here’s an example.

function variable takes nothing returns nothing
 local unit u = CreateUnit(…)
    //Other actions
    set u = other_unit //other_unit would be some other unit, don't use this example literally!
endfunction

Remember though, that old value isn’t set to that variable, so if you want 2 different units, use 2 different variables.

Ok, so I have my local variable. Now what?
-Now, use it! Here’s an example.

function KillUnit takes unit u returns nothing

-If you notice, KillUnit needs a unit. Now, you can fill this with many things, like GetTriggerUnit(), GetSpellAbilityUnit(), or any function which returns a unit. However, a variable can be a unit, so you can put that there instead. Here’s a side-by-side comparison.

function variable_testA takes nothing returns nothing
 local unit u = GetTriggerUnit()
    call KillUnit(u)
endfunction

function variable_testB takes nothing returns nothing
    call KillUnit(GetTriggerUnit())
endfunction

They both work, it's up to you to choose which way you prefer.

Naming variables

When naming variables, you can't just use any name. First off, the only characters you can use are any letter in the alphabet, any number, and the underscore character (_). The first letter in a variable name must be a letter, after that you can use numbers, letters, and underscores all you want. Let me make it clear that you can not use spaces in a variable name.

What about global variables?
-Global variables are created through the Variable Editor, inside the Trigger Editor. These variables can be used in any function, unlike locals. Example:

function A takes nothing returns nothing
call KillUnit(udg_u)
endfunction

function B takes nothing returns nothing
call KillUnit(udg_u)
endfunction

This is basically what it means. A variable starting with “udg_” usually means it is global. You can do this sort of thing with locals, but it isn't advised. If you need to refer to the same unit in a different function, there are methods of doing so which will be discussed later. The names of the variables you create are udg_variable_name. Each space in the variable name you enter in should be referred to with an underscore '_'

You mentioned Memory Leaks, what are those?
-Although these will be discussed in full later, it is good that you know now.

Edit by wyrmlord

Whenever a variable, handle, or string is created, the game must set aside space for it to use. To get rid of that space, there are various methods you can use depending on the object. For example, if you had a special effect, you could destroy it and free up any space it was using. Memory leaks occur when an object isn't able to be destroyed, and it will stay in memory until the end of the game. Another example: suppose I create another special effect, and no variable is set to it. The special effect will use up memory (even if it can't be seen), and since it's unable to be destroyed, it will continue to use memory until the end of the game. Local variables that aren't integers, reals, or boolean are like this too. The fix to them is simply setting them equal to null at the end of a function. Strings use up memory as well, but you can't do anything to stop them from doing so.

So how do I fix Memory Leaks?

Edit by wyrmlord

Memory leaks will be gone over in a later tutorial. If you're eager to learn about them, by all means skip to the lesson on memory leaks. However, I wouldn't suggest doing any major amounts of coding until you know more about them

I saw an option to make the variable an array. What’s that mean?
-An array is a variable with more than one option, per say. It’s like an index of that variable type, sort of like a library. To access the variables, you must set them to an index number, then retrieve them as such.
Example:

function variable_test takes nothing returns nothing
local unit array u
set u[1] = GetTriggerUnit()
set u[2] = GetSpellTargetUnit()
call KillUnit(u[1])
call KillUnit(u[2])
set u[1] = null
set u[2] = null
endfunction

Functions can also be fit into those brackets [] to set it to an integer.

Edit by wyrmlord

This is just to have multiple explanations of the same thing, for possibly confused readers. Arrays are basically a lot of variables squeezed into one. To be exact, 8192 variables. To declare an array in JASS, you would do something like this:

local integer array int_array

The difference is really just adding the word "array" before the variable name. You are unable to set the array to a value on the same line that you create it, keep in mind. Now, you'll need to know how to access each of the 8192 parts of the array. You do that like a normal variable, only you have brackets after the variable with an integer between them, which would be a number from 0 to 8191. If that's a bit confusing, here's an example:

local integer array myIntegers //declaring the integer array
    set myIntegers[0] = 5 //Setting the 0th slot in the array to 5
    set myIntegers[1] = myIntegers[0] + 2 //Setting the 1st slot in the array to the value in the 0th slot in the array + 2
    set myIntegers[myIntegers[1]] = 2 //This is just showing that you can use a variable inside the brackets as well, it doesn't have to be an array though

I would not recommend using arrays for a purpose as small as this. An array contains 8192 values, no more and no less. For something like this it's like killing a fly with a rocket launcher. (In other words, don't use arrays unless they are actually needed)

There you have it! Variables in a nutshell. If you want to see a list of all the variables, open up either common.j in the Patch.mpq file. Or if you're not sure how to do that, get a tool like JassCraft, and on the right side of the screen when you open it up is a search box and a long list. On the bottom of that list is "show options". Click that, and then uncheck everything in the "search for" box except types. You can now click "hide options" and search through the types of variables.

Edit by wyrmlord

There are a few main variable types: integer, real, string, boolean, and handle. I'm sure you know what an integer is, it's a whole number (including negatives) such as: 1, 145, -37. A real is a number with decimal places such as: 3.14, -15.78, 11.1134. A string, as you might already know can be thought of as a message or text: "Hello", "This is a string". A boolean has two values: true or false. A handle, you could say, is a reference to an object such as a unit. You don't direct use the handle type usually, but you use types that extend the handle type. This basically means that they are a specific type of handle. A handle is pretty much anything that isn't an integer, real, string, boolean. Handles include: units, special effects, timers, groups, players, and so on.

CHALLENGE:
Can you fill in this code with the correct variables? (this does not involve arrays)
The “_”’s represent where something needs to be filled in.

function variable_challenge takes nothing returns nothing
local ____ _ = GetTriggerUnit()
call KillUnit(_)
set _ = ____
endfunction

Good luck, and happy JASSing!
~Darkwulfv